feat: add claude code skills and subagents for CDK development#913
feat: add claude code skills and subagents for CDK development#913Patrick Nilan (pnilan) merged 10 commits intomainfrom
Conversation
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. 💡 Show Tips and TricksTesting This CDK VersionYou can test this version of the CDK using the following: # Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@pnilan/claude/add-skills-subagents#egg=airbyte-python-cdk[dev]' --help
# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch pnilan/claude/add-skills-subagentsPR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
|
There was a problem hiding this comment.
Pull request overview
Adds Claude Code configuration (skills + subagents) intended to streamline Airbyte Python CDK development workflows (research/explanations, diagrams, and PR authoring), and updates gitignore to exclude generated skill output.
Changes:
- Add three CDK-focused research subagents under
.claude/agents/. - Add four reusable skills under
.claude/skills/(explain, diagram, create-pr, generate-pr-description). - Ignore the root
/thoughtsdirectory used for generated outputs.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
.gitignore |
Ignores /thoughts output directory used by Claude skills. |
.claude/agents/cdk-code-researcher.md |
Defines a subagent for researching local CDK code internals. |
.claude/agents/cdk-schema-researcher.md |
Defines a subagent for tracing declarative schema → models → factory → runtime. |
.claude/agents/connector-researcher.md |
Defines a subagent for fetching/analyzing connectors from airbytehq/airbyte via gh. |
.claude/skills/explain/SKILL.md |
Adds an “explain CDK” skill with fast/full modes and report output instructions. |
.claude/skills/diagram/SKILL.md |
Adds a diagramming skill to generate Mermaid diagrams and save them under thoughts/diagrams/. |
.claude/skills/create-pr/SKILL.md |
Adds a skill to generate title/description and create PRs via gh pr create. |
.claude/skills/generate-pr-description/SKILL.md |
Adds a skill to generate PR descriptions from main...HEAD diffs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughThis pull request introduces a structured set of documentation files to guide Claude AI agents through various tasks on the Airbyte Python CDK codebase. It adds research agent instructions for exploring CDK code and connectors, skill definitions for creating pull requests, generating diagrams, explaining CDK concepts, and generating PR descriptions. The Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes The review involves validating consistency across eight new documentation files with varying complexity. While documentation-only, several files (diagram and explain skills) contain detailed procedural workflows and templates that warrant careful cross-file consistency checks. Wdyt on the grouping—would you prefer the skills and agents organized differently? 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (3)
.claude/skills/create-pr/SKILL.md (1)
68-88: Fenced code block missing a language identifier (MD040)The PR body template block at line 68 has no language tag, which triggers the
markdownlintMD040 warning. Wdyt — addmarkdownto keep linting clean?✏️ Proposed fix
- ``` + ```markdown ## What🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.claude/skills/create-pr/SKILL.md around lines 68 - 88, The fenced code block in the PR body template (the triple-backtick block containing "## What/How/Changes/Recommended Review Order") lacks a language tag and triggers markdownlint MD040; update that block by adding a language identifier (e.g., change the opening "```" to "```markdown") so the block is explicitly marked as Markdown and the linter warning is resolved..claude/skills/diagram/SKILL.md (1)
77-77: Several fenced code blocks are missing language identifiers (MD040)Lines 77, 110, 156, and 232 each open a code block without a language tag, which triggers the markdownlint MD040 warning. Wdyt —
textorplaintextwould silence the warnings without implying a specific language for the pseudo-code/template blocks?✏️ Proposed fixes
- ``` + ```text Task(subagent_type=...- ``` + ``` Flow diagrams saved to: ...🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.claude/skills/diagram/SKILL.md at line 77, Several fenced code blocks in SKILL.md open without a language tag (MD040); update each opening triple-backtick to include a neutral language identifier like text or plaintext. Specifically, locate the blocks that begin with the snippets "Task(subagent_type=..." and "Flow diagrams saved to: ..." (and the other two blocks at the noted positions) and change their fences from ``` to ```text (or ```plaintext) so markdownlint MD040 warnings are silenced while keeping the content as plain text..claude/skills/explain/SKILL.md (1)
98-102: Fenced code block missing a language identifier (MD040)The
gh apicommand block at line 98 has no language tag. Wdyt — addingbashhere would both satisfy markdownlint and give syntax highlighting for the shell commands?✏️ Proposed fix
-``` +```bash gh api repos/airbytehq/airbyte/contents/airbyte-integrations/connectors/source-{name} --jq '.[].name'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.claude/skills/explain/SKILL.md around lines 98 - 102, Add a language identifier to the fenced code block containing the three gh api commands by changing the opening fence from ``` to ```bash so the block reads ```bash and provides shell syntax highlighting for the commands `gh api repos/airbytehq/airbyte/contents/airbyte-integrations/connectors/source-{name}` and the subsequent manifest/metadata decode lines.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/create-pr/SKILL.md:
- Around line 84-88: The heredoc terminator `EOF` in the gh pr create example in
SKILL.md can be broken by indentation; update the example to use a heredoc-safe
approach by replacing the indented `gh pr create --body "$(cat <<'EOF' ... EOF
)"` pattern with a more robust `--body-file` invocation (e.g., using process
substitution or a temporary file) so the `<generated description>` is provided
reliably; locate the example containing the `gh pr create` command and `EOF` and
swap it to use `--body-file` (or an equivalent temp-file/printf approach) and
update the explanatory text accordingly.
In @.claude/skills/diagram/SKILL.md:
- Around line 76-82: The Task(...) invocations use an undefined subagent_type
"codebase-analyzer"; update those Task calls to use the existing agent name
"cdk-code-researcher" so the subagent resolves properly (replace
subagent_type="codebase-analyzer" with subagent_type="cdk-code-researcher" in
both Task(...) occurrences referenced in SKILL.md); ensure you update both
instances (the one around the "Trace the data flow..." prompt and the second
occurrence later in the file).
In @.claude/skills/generate-pr-description/SKILL.md:
- Line 40: Fix the typo in the SKILL.md template string: find the line
containing "only include files with significant changes. avoid including tests,
changelogs, documentation, and other files with trivial cahnges" and replace
"cahnges" with "changes" so the ordered list guidance reads correctly.
---
Nitpick comments:
In @.claude/skills/create-pr/SKILL.md:
- Around line 68-88: The fenced code block in the PR body template (the
triple-backtick block containing "## What/How/Changes/Recommended Review Order")
lacks a language tag and triggers markdownlint MD040; update that block by
adding a language identifier (e.g., change the opening "```" to "```markdown")
so the block is explicitly marked as Markdown and the linter warning is
resolved.
In @.claude/skills/diagram/SKILL.md:
- Line 77: Several fenced code blocks in SKILL.md open without a language tag
(MD040); update each opening triple-backtick to include a neutral language
identifier like text or plaintext. Specifically, locate the blocks that begin
with the snippets "Task(subagent_type=..." and "Flow diagrams saved to: ..."
(and the other two blocks at the noted positions) and change their fences from
``` to ```text (or ```plaintext) so markdownlint MD040 warnings are silenced
while keeping the content as plain text.
In @.claude/skills/explain/SKILL.md:
- Around line 98-102: Add a language identifier to the fenced code block
containing the three gh api commands by changing the opening fence from ``` to
```bash so the block reads ```bash and provides shell syntax highlighting for
the commands `gh api
repos/airbytehq/airbyte/contents/airbyte-integrations/connectors/source-{name}`
and the subsequent manifest/metadata decode lines.
…rcher in diagram skill Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…m breaking markdown Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
What
Adds a set of Claude Code skills and subagent definitions to streamline CDK development workflows. These provide automated PR creation, code explanation, diagram generation, and CDK-specific research capabilities.
How
Introduced Claude Code configuration files under
.claude/that define reusable skills (invoked via slash commands) and specialized subagents (spawned for research tasks). Each skill and agent has a focused prompt with structured instructions, key file references, and output templates tailored to the Airbyte Python CDK codebase.Changes
cdk-code-researcher— explores CDK internals (pagination, auth, retrievers, etc.)cdk-schema-researcher— traces YAML schema to Pydantic models to factory instantiationconnector-researcher— fetches and analyzes connector source code from the Airbyte monorepocreate-pr— creates GitHub PRs with auto-generated semantic titles and descriptionsgenerate-pr-description— generates PR descriptions from branch diffsexplain— researches and explains CDK components, architecture, and connector implementationsdiagram— generates Mermaid flowcharts and sequence diagrams for CDK code flows.gitignoreto exclude/thoughtsdirectory used for skill output filesRecommended Review Order
.claude/agents/cdk-code-researcher.md.claude/agents/cdk-schema-researcher.md.claude/agents/connector-researcher.md.claude/skills/explain/SKILL.md.claude/skills/diagram/SKILL.md.claude/skills/create-pr/SKILL.md.claude/skills/generate-pr-description/SKILL.mdSummary by CodeRabbit
Documentation
Chores